home *** CD-ROM | disk | FTP | other *** search
/ Tech Arsenal 1 / Tech Arsenal (Arsenal Computer).ISO / tek-02 / 6datgen0.zip / DG.DOC < prev    next >
Text File  |  1991-03-25  |  55KB  |  2,064 lines

  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.  
  25.  
  26.                                 The DataGen Kit
  27.                              USER REFERENCE MANUAL
  28.  
  29.                            Version 6.00 March 1991
  30.                       (C) Copyright 1989,90 by Tika Software.
  31.                               All Rights Reserved
  32.  
  33.                                  Tika Software
  34.                                 112 Village Path
  35.                                Lakewood, NJ 08701
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61. ────────────────────────────────────────────────────────────────────────────────
  62.  
  63.                                    DISCLAIMER
  64.  
  65.      Tika Software makes no representation or warranties with respect to
  66.      the contents hereof and specifically disclaims any implied warranties
  67.      to the suitability of this program for any particular purpose. You
  68.      must determine that yourself. In addition, you should understand that
  69.      using a program of this type on an IBM PC or compatible has inherent
  70.      risks and that you may inadvertently damage or destroy valuable pro-
  71.      grams or data. Tika Software expressly declines to assume liability
  72.      for any use of this program by you, and your use of this program con-
  73.      stitutes your agreement to hold us blameless. Tika Software reserves
  74.      the right to make changes from time to time in the context hereof
  75.      without obligation to notify any person or persons of such changes.
  76.  
  77.                                    TRADEMARK
  78.  
  79.      MS-DOS is a registered trademark of Microsoft Corporation.
  80.      PC-DOS is a registered trademark of IBM Corporation.
  81.      Turbo Pascal and Turbo Database Toolbox are registered trademarks of
  82.      Borland, Intl.
  83.      BTRIEVE is a registered trademark of SoftCraft, Inc.
  84.  
  85.  
  86.  
  87.  
  88.  
  89.  
  90.  
  91.  
  92.  
  93.  
  94.  
  95.  
  96.  
  97.  
  98.  
  99.  
  100.  
  101.  
  102.  
  103.  
  104.  
  105.  
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122. ────────────────────────────────────────────────────────────────────────────────
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.  
  130.                            DataGen Table of Contents
  131.  
  132.      Introduction.........................................................1
  133.      The DataGen Theory...................................................1
  134.      Why Use DataGen?.....................................................1
  135.      Mastering DataGen....................................................2
  136.      A Recipe for Instant DataGen Applications............................2
  137.      Explanation of Terms.................................................2
  138.  
  139.  
  140.      ScreenGen............................................................4
  141.      Command Syntax.......................................................4
  142.  
  143.      Overview.............................................................5
  144.           Syntax...............................................................5
  145.           Output...............................................................5
  146.  
  147.      Reference Guide......................................................7
  148.           File Specification...................................................7
  149.           Command Structure....................................................7
  150.           Screen Definition Section............................................7
  151.           Global Definition Section............................................8
  152.           Variable Definition Section.........................................13
  153.  
  154.      ScreenGen Sample Screens............................................15
  155.  
  156.  
  157.      DataGen.............................................................18
  158.      Overview............................................................19
  159.           Syntax..............................................................19
  160.           Output..............................................................19
  161.           Editing Turbo Source................................................20
  162.  
  163.      DataGen Reference...................................................21
  164.           File Specification..................................................21
  165.           Command Structure...................................................21
  166.  
  167.      Appendix A) Description of IO.TPU...................................23
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183. ────────────────────────────────────────────────────────────────────────────────
  184.  
  185.  
  186.  
  187.  
  188.  
  189.      Introduction
  190.  
  191.      DataGen enables the Turbo Pascal programmer to generate single screen
  192.      -- single datafile database applications quickly, efficiently, and
  193.      with a minimum of programming expertise. Developed with the simple ap-
  194.      plication in mind, DataGen facilitates rapid creation of such programs
  195.      as mailing, client and sales lists.
  196.  
  197.  
  198.      The DataGen Theory
  199.  
  200.      Many database generation systems presume that the datafile is the cen-
  201.      tral component of the database application. While this is often the
  202.      case in relational databases which manipulate several files, it com-
  203.      plicates the process of creating simple list applications.
  204.  
  205.      DataGen follows the premise that the Data Entry Screen is the pivotal
  206.      component of a database application, effectively mirroring the struc-
  207.      ture of the datafile. From a simple ascii screen definition file,
  208.      DataGen creates a full-function database, storing the items of the
  209.      data entry screen as fields in the database.
  210.  
  211.  
  212.      Why Use DataGen?
  213.  
  214.      DataGen generates accurate and thoroughly documented Turbo Pascal
  215.      source code.
  216.  
  217.      Once compiled (using Turbo Pascal 4.0 or higher) DataGen applications
  218.      execute independent of runtime modules, and background processes.1
  219.  
  220.      DataGen generates databases in BTRIEVE or Turbo Toolbox format
  221.  
  222.      Under BTRIEVE, DataGen applications run on a variety of Multi-user
  223.      Network environments, with full file and record locking.
  224.  
  225.      Applications which are developed using DataGen are free from royalty
  226.      restrictions.
  227.  
  228.      The typical DataGen full-function database can be developed in under
  229.      10 minutes.
  230.  
  231.      DataGen is a Turbo Pascal programming tool; it places no limitations
  232.      on the final database application. The scope of the final process is
  233.      bounded only by the skill of the Turbo Pascal programmer.
  234.  
  235.      ScreenGen (part of the DataGen Development Kit) generates screens in-
  236.      dependent of DataGen, and may be used in the development of both data-
  237.      base and non-database applications.
  238.  
  239.  
  240.      1BTRIEVE format databases require BTRIEVE to be loaded upon execution
  241.  
  242.  
  243.  
  244.  
  245.                DataGen Page 1 -- Copyright (C) Tika Software, Co.
  246. ────────────────────────────────────────────────────────────────────────────────
  247.  
  248.  
  249.      Mastering DataGen
  250.  
  251.      The DataGen Development Kit is made up of two separate processes:
  252.  
  253.      ScreenGen:         Data Entry Screen generator
  254.      DataGen:           Database generator
  255.  
  256.      Programmers of DataGen should begin by familiarizing themselves with
  257.      ScreenGen's Screen Development Language (SDL). DataGen utilizes
  258.      ScreenGen SDL source files to build a data storage system for informa-
  259.      tion passed to and from the screen.
  260.  
  261.  
  262.  
  263.      A Recipe For Instant DataGen Applications
  264.  
  265.      Step 1: Design a screen. I suggest you thoroughly cover the ScreenGen
  266.      section of this manual, however if you're impatient, as I am, flip
  267.      back and forth between the ScreenGen Syntax section of the Reference
  268.      manual, and the ScreenGen Sample Screen section. Good luck.
  269.  
  270.      Step 2: Follow the instructions listed in the Syntax section of the
  271.      DataGen Overview.
  272.  
  273.      Step 3: Execute the application. There, instant gratification. Do you
  274.      feel good about yourself? No, you feel cheap and empty inside... I
  275.      suggest that you go back and do it properly.
  276.  
  277.      Explanation of Terms
  278.  
  279.      Please refer to this list of definitions when covering the following
  280.      sections.
  281.  
  282.      <code_list>
  283.      One or more lines of valid (syntax correct) Turbo Pascal source code.
  284.  
  285.      <conditional>
  286.      A Turbo Pascal conditional clause.
  287.  
  288.      Example: In the Turbo Pascal statement
  289.      If Color = 'Red' Then Exit
  290.      Color = 'Red' is the conditional clause.
  291.  
  292.      get_function()
  293.      A get_function() accepts user input, allows the user to edit the in-
  294.      put, and returns as the value of the function a specific Turbo Pascal
  295.      data type. The get_function() is the heart of io.tpu, a module of sub-
  296.      routines which form the basis of ScreenGen2. Three get_function()s
  297.      correspond to the three primary Turbo Pascal data types.
  298.  
  299.  
  300.      2The get_function()s are detailed in Appendix A, along with all of the
  301.      subroutines of io.tpu.
  302.  
  303.  
  304.  
  305.  
  306.               DataGen Page 2 -- Copyright (C) Tika Software, Co.
  307. ────────────────────────────────────────────────────────────────────────────────
  308.  
  309.         get_string(default, option_list)
  310.         get_integer(default, option_list)
  311.         get_real(default, option_list);
  312.  
  313.      The fourth, get_menu(), allows the user to select from a highlighted
  314.      bar of choices, and returns a byte corresponding to the choice
  315.      selected.
  316.  
  317.         get_menu( menu, menuhelp, default, option_list)
  318.  
  319.      <menu>
  320.      A string sent as the first parameter in a get_menu() function call.
  321.      See the description of parameters for get_menu() in Appendix A.
  322.  
  323.      <menuhelp>
  324.      A string sent as the second parameter in a get_menu() function call.
  325.      See the description of parameters for get_menu() in Appendix A.
  326.  
  327.      #STATEMENT
  328.      A ScreenGen Reserved word, prefixed by the pound sign (#) and followed
  329.      by any number of parameters.
  330.  
  331.  
  332.  
  333.  
  334.  
  335.  
  336.  
  337.  
  338.  
  339.  
  340.  
  341.  
  342.  
  343.  
  344.  
  345.  
  346.  
  347.  
  348.  
  349.  
  350.  
  351.  
  352.  
  353.  
  354.  
  355.  
  356.  
  357.  
  358.  
  359.  
  360.  
  361.  
  362.  
  363.  
  364.  
  365.  
  366.  
  367.               DataGen Page 3 -- Copyright (C) Tika Software, Co.
  368. ────────────────────────────────────────────────────────────────────────────────
  369.      ScreenGen
  370.  
  371.      ScreenGen assists the Turbo Pascal programmer who is called upon to
  372.      create data entry screens. Executed from the command line, ScreenGen
  373.      accepts a ScreenGen source file as input and generates a Turbo Pascal
  374.      source file capable of executing a full-function data entry screen.
  375.  
  376.                          SG.EXE                        TPC.EXE
  377.      ScreenGen -->       *----*    -->       Turbo Pascal        *-----* --
  378.      >    Object Code
  379.      Source Code    -->       *----*    -->       Source Code
  380.      *-----*   -->  (.EXE File)
  381.                          SG.EXE                        TPC.EXE
  382.                (ScreenGen Generator)              (Turbo Pascal Compiler)
  383.  
  384.      Command syntax
  385.  
  386.      SG <SOURCE_FILE> <OUTPUT_FILE>3
  387.  
  388.  
  389.  
  390.  
  391.      3Although not required, it is strongly suggested that ScreenWrite
  392.      source files be tagged .SW, that is: <FILENAME>.SW. ScreenWrite output
  393.      files should be tagged .SCR, that is: <FILENAME>.SCR. Thus the command
  394.      syntax becomes:
  395.      SW <SOURCE_FILE>.SW <OUTPUT_FILE>.SCR
  396.  
  397.  
  398.  
  399.  
  400.  
  401.  
  402.  
  403.  
  404.  
  405.  
  406.  
  407.  
  408.  
  409.  
  410.  
  411.  
  412.  
  413.  
  414.  
  415.  
  416.  
  417.  
  418.  
  419.  
  420.  
  421.  
  422.  
  423.  
  424.  
  425.  
  426.  
  427.  
  428.               DataGen Page 4 -- Copyright (C) Tika Software, Co.
  429. ────────────────────────────────────────────────────────────────────────────────
  430.      ScreenGen Overview
  431.  
  432.      Syntax
  433.  
  434.      <Screen Definition Section>
  435.      ##
  436.      <Global Definition Section>
  437.      <Variable Definition Section>
  438.      <END OF FILE>
  439.  
  440.      <Screen Definition Section>
  441.      A Picture of the Screen.
  442.  
  443.      <Global Definition Section>
  444.      A series of #STATEMENTS which detail characteristics global to the
  445.      screen. The Programmer may specify the format of the generated code,
  446.      as well as defaults for screen functionality.
  447.  
  448.      <Variable Definition Section>
  449.      A series of #DEFINE statements which assign variable names to the
  450.      fields identified in the <Screen Definition Section>. Additional
  451.      #STATEMENTS assign characteristics to the variables defined and enable
  452.      the user to specify input functionality for a given field.
  453.  
  454.      Output
  455.  
  456.      ScreenGen has the ability to generate a screen in two formats.
  457.  
  458.      1) non_procedural
  459.         A series of get_function() calls, one per field.
  460.  
  461.      2) procedural
  462.         A complete Turbo Pascal procedure or function.
  463.  
  464.      [procedure | function] <screen_title>( display_status: string[] )[ :
  465.      byte ];
  466.      <declaration section>
  467.      begin
  468.                 with <data_record> do begin
  469.  
  470.                 if \1   Display non-fields (background)
  471.                 if \2   Display default field values.
  472.                 if \3   repeat
  473.                                 Edit Data
  474.                         until <escape_conditional>
  475.                 end; {with}
  476.      end; {subroutine}
  477.  
  478.      Selecting a procedural screen, the programmer generates a fully func-
  479.      tional sub-routine, which can be $Included in a Turbo Pascal Module.
  480.      The procedural screen enables an end-user to view a screen, fill the
  481.      screen and transfer the results to variables defined by the program-
  482.      mer.
  483.  
  484.  
  485.  
  486.  
  487.  
  488.  
  489.               DataGen Page 5 -- Copyright (C) Tika Software, Co.
  490. ────────────────────────────────────────────────────────────────────────────────
  491.      The screen performs three functions.
  492.      1) Display non-field (background) information.
  493.      2) Display default field values -- those values currently contained in
  494.      the Turbo variables corresponding to the fields.
  495.      3) Allow the user to step through each field adding or changing data.
  496.  
  497.      The programmer selects the function or functions desired by passing
  498.      '\1', '\2', and/or '\3' in the parameter display_status. For example,
  499.      A call to
  500.                         data_screen('\1\2');
  501.      displays the border information, and field values of a database, while
  502.      a call to:
  503.                         data_screen('\3');
  504.      allows the user to edit database screen fields.
  505.  
  506.  
  507.  
  508.  
  509.  
  510.  
  511.  
  512.  
  513.  
  514.  
  515.  
  516.  
  517.  
  518.  
  519.  
  520.  
  521.  
  522.  
  523.  
  524.  
  525.  
  526.  
  527.  
  528.  
  529.  
  530.  
  531.  
  532.  
  533.  
  534.  
  535.  
  536.  
  537.  
  538.  
  539.  
  540.  
  541.  
  542.  
  543.  
  544.  
  545.  
  546.  
  547.  
  548.  
  549.  
  550.               DataGen Page 6 -- Copyright (C) Tika Software, Co.
  551. ────────────────────────────────────────────────────────────────────────────────
  552.      ScreenGen Reference Guide
  553.  
  554.      Readers of this section should first examine the ScreenGen Overview.
  555.  
  556.      File Specification
  557.  
  558.      To run ScreenGen, you need load only the ScreenGen executable file:
  559.      SG.EXE
  560.  
  561.      Code generated by ScreenGen must be linked to IO.TPU before executing.
  562.  
  563.      Command Structure and Syntax Detail (SDL)
  564.  
  565.      <Screen Definition Section>
  566.  
  567.      The <Screen Definition Section> is made up of up to 24 <Screen Defini-
  568.      tion Line>s each containing:
  569.  
  570.      1) fields
  571.      2) non-fields (background)
  572.  
  573.      Fields consist of a combination of @s and non-blank format characters.
  574.      Examples of valid fields are:
  575.                 @@@@@@@@@       (field of length 9)
  576.                 @@@-@@-@@@@     (formatted field, length 10)
  577.  
  578.      Formatted fields are useful when storing items such as social security
  579.      numbers, as designated by the example above, dates (@@/@@/@@), and
  580.      telephone numbers ((@@@)-@@@-@@@@). The only restriction placed on a
  581.      formatted field is that it contain no blank characters, otherwise
  582.      ScreenGen will mistakenly interpret it as two separate fields.
  583.  
  584.      non-fields (background) are made up of any character beside the @ sym-
  585.      bol. Field titles, borders and blank lines are all examples of back-
  586.      ground.
  587.  
  588.      An example of a <Screen Definition Line> for an employee database
  589.      might be:
  590.  
  591.      Name: @@@@@@@@@@@@@@@@     Phone: (@@@)-@@@-@@@@   B-Day: @@/@@/@@
  592.  
  593.      The Phone and Birthday fields are formatted fields and will be stored
  594.      as string[10] and string[6] respectively.
  595.  
  596.      'Name:', 'Phone:', and 'B-Day:' comprise the background (non-field)
  597.      items on the line.
  598.  
  599.  
  600.  
  601.  
  602.  
  603.  
  604.  
  605.  
  606.  
  607.  
  608.  
  609.  
  610.  
  611.               DataGen Page 7 -- Copyright (C) Tika Software, Co.
  612. ────────────────────────────────────────────────────────────────────────────────
  613.      <Global Definition Section>: OPTIONAL
  614.  
  615.      The <Global Definition Section> defines information pertinent to the
  616.      entire screen.
  617.  
  618.  
  619.      #DATABASE, #SCREEN, #PROCEDURE and #FUNCTION are subroutine designa-
  620.      tion statements. They instruct ScreenGen to generate a procedural
  621.      screen. Absence of a subroutine designation #STATEMENT results in the
  622.      generation of a non-procedural screen (a linear series of get_func-
  623.      tion() calls). In the following examples, <file_title> refers to the
  624.      SG source file without the extension.
  625.  
  626.      #DATABASE <database_title>
  627.      Generates a Turbo Pascal procedure in this format:
  628.      procedure <database_title>_screen( display_status : string[15]);
  629.         begin
  630.                 with <database_title>_data do begin
  631.                 .
  632.                 if \1 then draw screen background
  633.                 .
  634.                 if \2 then echo default fields
  635.                 .
  636.                 if \3 then repeat
  637.                         get_function() calls
  638.                 until <escape_conditional>
  639.                 .
  640.                 end; {with}
  641.         end; {procedure}
  642.      This option is generally used in conjunction with DataGen.
  643.      <database_title> default = <file_title>
  644.      <escape_conditional> default = 'in_keycode = k_escape'
  645.  
  646.      #SCREEN <screen_title>
  647.      Generates a Turbo Pascal procedure in this format:
  648.      procedure <screen_title>( display_status : string[15]);
  649.         begin
  650.                 if \1 then draw screen background
  651.                 .
  652.                 if \2 then echo default fields
  653.                 .
  654.                 if \3 then repeat
  655.                         get_function() calls
  656.                 until <escape_conditional>
  657.         end; {procedure}
  658.  
  659.      <screen_title> default = <file_title>_screen
  660.      <escape_conditional> default = 'in_keycode = k_escape'
  661.  
  662.      #PROCEDURE <procedure_title>
  663.      Generates a Turbo Pascal procedure in this format:
  664.      procedure <procedure_title>( display_status : string[15]);
  665.         begin
  666.                 if \1 then draw screen background
  667.  
  668.  
  669.  
  670.  
  671.  
  672.               DataGen Page 8 -- Copyright (C) Tika Software, Co.
  673. ────────────────────────────────────────────────────────────────────────────────
  674.                 .
  675.                 if \2 then echo default fields
  676.                 .
  677.                 if \3 then repeat
  678.                         get_function() calls
  679.                 until <escape_conditional>
  680.         end; {procedure}
  681.  
  682.      <procedure_title> default = <file_title>_screen
  683.      <escape_conditional> default = 'in_keycode = k_escape'
  684.  
  685.  
  686.      #FUNCTION <function_title>
  687.      Generates a Turbo Pascal function in this format:
  688.      function <function_title>( display_status : string[15]) : byte;
  689.         begin
  690.                 if \1 then draw screen background
  691.                 .
  692.                 if \2 then echo default fields
  693.                 .
  694.                 if \3 then repeat
  695.                         get_function() calls
  696.                 until <escape_conditional>
  697.         end; {procedure}
  698.  
  699.      <function_title> default = <file_title>_screen
  700.      <escape_conditional> default = 'in_keycode = k_escape'
  701.      The return value of the function should be set by the programmer using
  702.      #BEFORE/#AFTER.
  703.  
  704.      #OVERLAY
  705.      Generates an Overlay Procedure or function. Must be used in conjunc-
  706.      tion with #DATABASE, #SCREEN, #PROCEDURE or #FUNCTION.
  707.  
  708.      #WITH <record_title>
  709.      Generates a with statement. Must be used in conjunction with #SCREEN,
  710.      #PROCEDURE or #FUNCTION (#DATABASE automatically forces the generation
  711.      of a with statement).
  712.      <record_title> default = <file_title>_data
  713.  
  714.      #ESCAPE <escape_conditional>
  715.      Default: in_keycode = k_escape
  716.      Sets the <escape_conditional> in the generated procedure/function (see
  717.      above).
  718.  
  719.      #TYPE [ String | Integer | Real ]
  720.      Default: String
  721.      Sets the default data_type = 'String', 'Integer' or 'Real'.
  722.  
  723.  
  724.  
  725.  
  726.  
  727.  
  728.  
  729.  
  730.  
  731.  
  732.  
  733.               DataGen Page 9 -- Copyright (C) Tika Software, Co.
  734. ────────────────────────────────────────────────────────────────────────────────
  735.  
  736.      #BEFORE <code_list>
  737.      #AFTER <code_list>
  738.      Used to insert Turbo Pascal source into the ScreenGen output file.
  739.      Placement of the code depends upon placement of the #BEFORE/#AFTER
  740.      statement. If we consider #SUBROUTINE to be #DATABASE, #SCREEN, #PRO-
  741.      CEDURE, or #FUNCTION, then placement of #BEFORE/#AFTER code in the
  742.      resultant procedure/function follows.
  743.  
  744.  
  745.      CASE 1: #BEFORE/#AFTER follows #SUBROUTINE.
  746.  
  747.      From the source code:
  748.  
  749.      #SUBROUTINE foo
  750.      #BEFORE <before_code>
  751.         .
  752.         .
  753.      #AFTER <after_code>
  754.         .
  755.         .
  756.      ##
  757.  
  758.      ScreenGen generates the Turbo Pascal code:
  759.  
  760.      subroutine foo
  761.      begin
  762.                 {with foo_data do begin [if designated])
  763.                 <before_code>
  764.                         .
  765.                         .
  766.                 body of subroutine...
  767.                         .
  768.                         .
  769.                 <after_code>
  770.                         .
  771.                         .
  772.                 {end with, if designated}
  773.      end; {subroutine}
  774.  
  775.  
  776.  
  777.  
  778.  
  779.  
  780.  
  781.  
  782.  
  783.  
  784.  
  785.  
  786.  
  787.  
  788.  
  789.  
  790.  
  791.  
  792.  
  793.  
  794.              DataGen Page 10 -- Copyright (C) Tika Software, Co.
  795. ────────────────────────────────────────────────────────────────────────────────
  796.  
  797.      CASE 2: #BEFORE/#AFTER Precedes #SUBROUTINE
  798.  
  799.      From the source code:
  800.  
  801.      #BEFORE <before_code>
  802.         .
  803.         .
  804.      #AFTER <after_code>
  805.         .
  806.         .
  807.  
  808.      #SUBROUTINE foo
  809.      ##
  810.  
  811.      ScreenGen generates the Turbo Pascal code:
  812.  
  813.                 <before_code>
  814.                         .
  815.                         .
  816.      subroutine foo
  817.      begin
  818.                 {with foo_data do begin [if designated])
  819.                 body of subroutine...
  820.                         .
  821.                         .
  822.                 {end with, if designated}
  823.      end; {subroutine}
  824.  
  825.                 <after_code>
  826.                         .
  827.                         .
  828.  
  829.      #DECLARE <code_list>
  830.      Used to insert variable declarations into the ScreenGen output file.
  831.      Code is placed in the declaration section of the resultant subroutine.
  832.  
  833.      From the source code:
  834.  
  835.      #SUBROUTINE
  836.      #DECLARE <declaration_code_list>
  837.         .
  838.         .
  839.      ##
  840.  
  841.      ScreenGen generates the Turbo Pascal code:
  842.  
  843.      subroutine foo
  844.      <declaration code_list>
  845.         .
  846.         .
  847.      begin
  848.                 {with foo_data do begin [if designated])
  849.                 body of subroutine...
  850.  
  851.  
  852.  
  853.  
  854.  
  855.              DataGen Page 11 -- Copyright (C) Tika Software, Co.
  856. ────────────────────────────────────────────────────────────────────────────────
  857.                         .
  858.                         .
  859.                 {end with, if designated}
  860.      end; {subroutine}
  861.  
  862.  
  863.  
  864.  
  865.  
  866.  
  867.  
  868.  
  869.  
  870.  
  871.  
  872.  
  873.  
  874.  
  875.  
  876.  
  877.  
  878.  
  879.  
  880.  
  881.  
  882.  
  883.  
  884.  
  885.  
  886.  
  887.  
  888.  
  889.  
  890.  
  891.  
  892.  
  893.  
  894.  
  895.  
  896.  
  897.  
  898.  
  899.  
  900.  
  901.  
  902.  
  903.  
  904.  
  905.  
  906.  
  907.  
  908.  
  909.  
  910.  
  911.  
  912.  
  913.  
  914.  
  915.  
  916.              DataGen Page 12 -- Copyright (C) Tika Software, Co.
  917. ────────────────────────────────────────────────────────────────────────────────
  918.      <Variable Definition Section>
  919.  
  920.      For each field defined in the <Screen Definition Section> ScreenGen
  921.      requires a #DEFINE statement to appear in the <Variable Definition
  922.      Section>. #STATEMENTS which follow the #DEFINE for a given variable
  923.      act as qualifying commands for that variable.
  924.  
  925.      The following is a list of legal <Variable Definition Section> #STATE-
  926.      MENTS with descriptions:
  927.  
  928.      #DEFINE <variable>
  929.      Assigns the name <variable> to the next Field as indicated in the
  930.      <Screen Definition Section>. A get_function is generated for the <var-
  931.      iable> unless it is designated #DISPLAY (see #DISPLAY below). Fields
  932.      are assigned in a top down manner from left to right.
  933.  
  934.      #OPTIONS <option_list>
  935.      Appends <option_list> to the get_function() for the corresponding
  936.      #DEFINEd variable.
  937.  
  938.      #BEFORE <code_list>
  939.      <code_list> will be executed prior to execution of the get_function()
  940.      for the #DEFINEd variable.
  941.  
  942.      #AFTER <code_list>
  943.      <code_list> will be executed following execution of the get_function()
  944.      for the #DEFINEd variable.
  945.  
  946.      #MENU <menu>
  947.      a get_menu() call will be generated for the #DEFINEd variable with
  948.      <menu> as the first parameter.
  949.  
  950.      #PROMPT <menu>
  951.      a get_menu() call will be generated for the #DEFINEd variable with
  952.      <menu> as the first parameter, and \px and \py set to the field loca-
  953.      tion. As a result the menu selection appears in the field location as
  954.      well as being highlighted on the menu.
  955.  
  956.      ## <comment_list>
  957.      Allows the user of SG to comment source code. <comment_list> is not
  958.      transferred to the resultant Turbo source. ## also separates the
  959.      <Screen Definition Section> from the <Variable Definition Section>.
  960.  
  961.      #VIEWORDER <vieworder_spec>
  962.      specifies the
  963.  
  964.      #VERIFY <turbo_conditional>
  965.      After editing the #DEFINEd field, this <turbo_conditional> is tested,
  966.      before continuing.
  967.  
  968.      Example:   #DEFINE this_field
  969.                 #VERIFY this_field > 17
  970.  
  971.      #ERROR <error_message>
  972.  
  973.  
  974.  
  975.  
  976.  
  977.              DataGen Page 13 -- Copyright (C) Tika Software, Co.
  978. ────────────────────────────────────────────────────────────────────────────────
  979.      <error_message>  is displayed if the <turbo_conditional> of the
  980.      #VERIFY command is not met.
  981.  
  982.      Example:   #DEFINE this_field
  983.                 #VERIFY this_field > 17
  984.                 #ERROR  This field must be at least 18, you twit.
  985.  
  986.      #DISPLAY
  987.      Sets the #DEFINEd variable to display only. No editing of the field
  988.      will be allowed.
  989.  
  990.      #HELP <menuhelp>
  991.      If the #DEFINEd field is a menu field, <menuhelp> is offered as the
  992.      second parameter of the get_menu() call.
  993.  
  994.      #TYPE [ String | Integer | Real ]
  995.      Default: String
  996.      parameter = String         : A get_string() call is generated.
  997.      parameter = Integer                : A get_integer() call is genera-
  998.      ted.
  999.      parameter = Real           : A get_real() call is generated.
  1000.  
  1001.      To generate a get_menu() call, see #MENU.
  1002.  
  1003.      #VIDEO [ bright | dim | reverse | no_color ]
  1004.      Default: no_color
  1005.      Sets the display intensity for a field.
  1006.  
  1007.      #VIEWORDER <view_list>
  1008.      Allows the programmer to specify the next field to be edited for each
  1009.      exit keystroke (e.g. carriage return, cursor up...). By default, a
  1010.      call to vieworder() (part of io.tpu) is generated following each
  1011.      get_function(). ScreenGen tries to best guess the intentions of the
  1012.      programmer regarding the order of field traversal, based on top-down,
  1013.      left-right. Under certain circumstances, it may be necessary to change
  1014.      the default order of field traversal. <view_list> is a string contain-
  1015.      ing one or more of the following:
  1016.  
  1017.         \crn    On carriage return goto field n
  1018.         \ucn    On up cursor goto field n
  1019.         \dcn    On down cursor goto field n
  1020.         \tabn   On tab goto field n
  1021.         \btabn  On backtab (Shift+tab) goto field n
  1022.         \escn   On escape goto field n
  1023.  
  1024.      In all cases, n must be a valid field number. Fields are implicitly
  1025.      numbered starting from 1, top-left to bottom-right.
  1026.  
  1027.  
  1028.  
  1029.  
  1030.  
  1031.  
  1032.  
  1033.  
  1034.  
  1035.  
  1036.  
  1037.  
  1038.              DataGen Page 14 -- Copyright (C) Tika Software, Co.
  1039. ────────────────────────────────────────────────────────────────────────────────
  1040.  
  1041.      ScreenGen Sample Screens
  1042.  
  1043.      Screen 1:  Employee Screen
  1044.      Name:      @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
  1045.      Street1:   @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
  1046.      Street2:   @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
  1047.      City:      @@@@@@@@@@@@@@@@@@@@@@@@  State: @@  Zip: @@@@@@@@@@@
  1048.      Phone:     @@@-@@@-@@@@    Social Security:        @@@-@@-@@@@
  1049.  
  1050.      ##
  1051.      ##         Global Declaration Section
  1052.      ##
  1053.  
  1054.      #screen employee_screen
  1055.      #with employee_data_record
  1056.  
  1057.      ##
  1058.      ##         Variable Declaration Section
  1059.      ##
  1060.  
  1061.      #define name
  1062.      ## Capitalize the First letter of name
  1063.         #option \g
  1064.      ## Highlight the Name for easy scanning
  1065.         #video bright
  1066.      #define street1
  1067.      #define street2
  1068.      #define city
  1069.      #define state
  1070.      ## Force the characters of state to uppercase
  1071.         #options \u
  1072.      #define zip
  1073.      #define phone
  1074.      #define soc_sec
  1075.      ## Although stored as a string, a social security number contains
  1076.      ## only numeric digits
  1077.         #options \ci
  1078.  
  1079.  
  1080.  
  1081.  
  1082.  
  1083.  
  1084.  
  1085.  
  1086.  
  1087.  
  1088.  
  1089.  
  1090.  
  1091.  
  1092.  
  1093.  
  1094.  
  1095.  
  1096.  
  1097.  
  1098.  
  1099.              DataGen Page 15 -- Copyright (C) Tika Software, Co.
  1100. ────────────────────────────────────────────────────────────────────────────────
  1101.      ScreenGen Sample Screens, Continued
  1102.  
  1103.      Screen2: Sales Screen              Records on File:        @@@@@
  1104.      Company:   @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
  1105.      Contact:   @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
  1106.  
  1107.      Phone: (w) @@@-@@@-@@@@    (h) @@@-@@@-@@@@
  1108.  
  1109.      Date of First Call:        @@/@@/@@ Last:  @@/@@/@@
  1110.      Resolution of Call: @@@@@@@@@@@@@@@@
  1111.  
  1112.      Notes:     @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
  1113.      @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
  1114.      @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
  1115.      ##
  1116.      ## Global Definition Section
  1117.      ##
  1118.      #procedure sales_screen
  1119.      #with sales_data
  1120.      ##
  1121.      ## Variable Definition Section
  1122.      ##
  1123.      #define usedrecs( sales_file )
  1124.      ##
  1125.      ## Sometimes, variables may actually be subroutine calls
  1126.      ## which return a specific Turbo type.
  1127.      ## usedrecs() is a Turbo Database Toolbox routine.
  1128.      ## It is of type integer, and must be set to display only.
  1129.      ##
  1130.         #type integer
  1131.         #display
  1132.  
  1133.      #define company
  1134.         #options \g
  1135.      #define contact
  1136.      #define work_phone
  1137.      #define home_phone
  1138.      #define first_call_date
  1139.      #define last_call_date
  1140.      #define call_resolution
  1141.         #prompt \1Call Again\2No Deal\3Sale
  1142.         #help \1When at First you don''t succeed\2Forget it\3Yeah!
  1143.      ##
  1144.      ## Notice the use of the double '' in the #help call.
  1145.      ## When the #help is converted, the parameter becomes a Turbo
  1146.      ## Pascal string. Since a single quotation mark signifies
  1147.      ## the end of a string, a double mark must be used.
  1148.      ##
  1149.      #define notes1
  1150.      #define notes2
  1151.      #define notes3
  1152.  
  1153.  
  1154.  
  1155.  
  1156.  
  1157.  
  1158.  
  1159.  
  1160.              DataGen Page 16 -- Copyright (C) Tika Software, Co.
  1161. ────────────────────────────────────────────────────────────────────────────────
  1162.      ScreenGen Sample Screens, Continued
  1163.  
  1164.      Screen 3: Help Screen
  1165.  
  1166.      This is an example of how a ScreenGen programmer might define a Help
  1167.      Screen. It contains a useful information about running an application
  1168.      that would be brought up under a [HELP] option. In this example, we
  1169.      direct that the screen be generated as a function, returning a byte to
  1170.      the calling routine which signifies display next (1), or Return to Ap-
  1171.      plication (2). The Turbo Pascal variable exit_menu is local to the
  1172.      generated function, declared using #DECLARE, initialized in the #BE-
  1173.      FORE code and passed to the function in the #AFTER code.
  1174.  
  1175.      Turn off VCR                               ----    ALT-F1
  1176.      Make pizza                         ----    ALT-F2
  1177.      Take my wife, please                       ----    ALT-F3
  1178.  
  1179.  
  1180.  
  1181.  
  1182.      @@@@@@@@@@
  1183.      ##
  1184.      ## Global Definition Section
  1185.      ##
  1186.      #function help_screen
  1187.      #declare var exit_menu : byte;
  1188.      #before exit_menu := 1;
  1189.      #after help_screen := exit_menu;
  1190.  
  1191.      ## Variable Definition Section
  1192.  
  1193.      #define exit_menu
  1194.         #menu \1Next\2Return
  1195.         #help \1Display Next Help Screen\2Return to Application
  1196.  
  1197.  
  1198.  
  1199.  
  1200.  
  1201.  
  1202.  
  1203.  
  1204.  
  1205.  
  1206.  
  1207.  
  1208.  
  1209.  
  1210.  
  1211.  
  1212.  
  1213.  
  1214.  
  1215.  
  1216.  
  1217.  
  1218.  
  1219.  
  1220.  
  1221.              DataGen Page 17 -- Copyright (C) Tika Software, Co.
  1222. ────────────────────────────────────────────────────────────────────────────────
  1223.  
  1224.      DataGen
  1225.  
  1226.      DataGen assists Turbo Pascal programmers who wish to create simple
  1227.      database applications. Executed from the command line, DataGen accepts
  1228.      a DataGen source file as input and generates a Turbo Pascal Source
  1229.      file capable of executing a full-function database. Source code may be
  1230.      generated in TURBO DATABASE TOOLBOX, or BTRIEVE format.
  1231.  
  1232.                          DG.EXE                        TPC.EXE
  1233.      DataGen   -->       *----*    -->       Turbo Pascal        *-----* --
  1234.      >    Object Code
  1235.      Source Code    -->       *----*    -->       Source Code
  1236.      *-----*   -->  (.EXE File)
  1237.                          DG.EXE                        TPC.EXE
  1238.                (DataGen Generator)           (Turbo Pascal Compiler)
  1239.  
  1240.      Command syntax
  1241.  
  1242.      DG <SOURCE_FILE> [/b]
  1243.  
  1244.      The /b parameter indicates generation of a database in BTRIEVE format.
  1245.  
  1246.  
  1247.  
  1248.  
  1249.  
  1250.  
  1251.  
  1252.  
  1253.  
  1254.  
  1255.  
  1256.  
  1257.  
  1258.  
  1259.  
  1260.  
  1261.  
  1262.  
  1263.  
  1264.  
  1265.  
  1266.  
  1267.  
  1268.  
  1269.  
  1270.  
  1271.  
  1272.  
  1273.  
  1274.  
  1275.  
  1276.  
  1277.  
  1278.  
  1279.  
  1280.  
  1281.  
  1282.              DataGen Page 18 -- Copyright (C) Tika Software, Co.
  1283. ────────────────────────────────────────────────────────────────────────────────
  1284.  
  1285.      DataGen Overview
  1286.  
  1287.      Syntax
  1288.  
  1289.      DataGen syntax is a subset of ScreenGen source syntax. To create a
  1290.      database using DataGen, follow these steps:
  1291.  
  1292.      1)   Design a screen using ScreenGen SDL
  1293.           Tag the file .sg, that is <SOURCE_FILE>.sg
  1294.  
  1295.      2)   Make the following changes to the ScreenGen source:
  1296.           a)   include the command #DATABASE in the <Global Definition Sec-
  1297.      tion>
  1298.  
  1299.           b)   using #INDEX, label each variable that you wish to utilize
  1300.                as a search key. The #INDEX is a <Variable Definition Sec-
  1301.                tion> #STATEMENT and should be included following the
  1302.                #DEFINE statement for a given variable. At least one vari-
  1303.                able must be #INDEXed per database. #INDEXed variables must
  1304.                be of #TYPE string.
  1305.  
  1306.      3)   Execute:  DG <SOURCE_FILE>.sg
  1307.           Execute:  Make -f<SOURCE_FILE>.mkf
  1308.  
  1309.      DataGen creates the executable file <SOURCE_FILE>.exe. Run this file
  1310.      to execute the database.
  1311.  
  1312.      Output
  1313.  
  1314.      DataGen generates database code in two formats.
  1315.  
  1316.      TURBO DATABASE TOOLBOX format
  1317.      BTRIEVE format
  1318.  
  1319.      DataGen creates three files from <SOURCE_FILE>.sg:
  1320.  
  1321.      <SOURCE_FILE>.pas   : Turbo Pascal .pas file
  1322.      <SOURCE_FILE>.typ   : Record Definition Include file to <SOUR-
  1323.      CE_FILE>.pas
  1324.      <SOURCE_FILE>.mkf   : Makefile for <SOURCE_FILE>.exe
  1325.  
  1326.  
  1327.      For each field #DEFINEd in <SOURCE_FILE>.sg, DataGen generates a Turbo
  1328.      Pascal identifier in <SOURCE_FILE>.typ. Each identifier is part of a
  1329.      Record called
  1330.      <SOURCE_FILE>_structure. For example, the .sg file
  1331.      geneva.sg:
  1332.  
  1333.      Name: @@@@@@@@@@@@@@@@@@@@@@@@@
  1334.      Rank:     @@@@@@@@@@     Serial Number: @@@@@@@@@@@-@@@
  1335.      ##
  1336.      #database
  1337.      #define name
  1338.  
  1339.  
  1340.  
  1341.  
  1342.  
  1343.              DataGen Page 19 -- Copyright (C) Tika Software, Co.
  1344. ────────────────────────────────────────────────────────────────────────────────
  1345.           #index
  1346.      #define rank
  1347.      #define serial_number
  1348.  
  1349.      yields the .typ file geneva.typ
  1350.  
  1351.      type geneva_structure = record
  1352.           status : longint;
  1353.           name : string[25];
  1354.           rank : string[10];
  1355.           serial_number : string[14];
  1356.      end; {record}
  1357.  
  1358.      The status field is generated for TURBO DATABASE TOOLBOX format data-
  1359.      bases only, and is used to track deleted records.
  1360.  
  1361.      Editing Turbo Source
  1362.  
  1363.      Once DataGen generates the source files, they may be edited prior to
  1364.      compilation. To do so, one should have a working knowledge of io.tpu,
  1365.      as a significant amount of the resultant source calls subroutines
  1366.      within the i/o module.
  1367.  
  1368.  
  1369.  
  1370.  
  1371.  
  1372.  
  1373.  
  1374.  
  1375.  
  1376.  
  1377.  
  1378.  
  1379.  
  1380.  
  1381.  
  1382.  
  1383.  
  1384.  
  1385.  
  1386.  
  1387.  
  1388.  
  1389.  
  1390.  
  1391.  
  1392.  
  1393.  
  1394.  
  1395.  
  1396.  
  1397.  
  1398.  
  1399.  
  1400.  
  1401.  
  1402.  
  1403.  
  1404.              DataGen Page 20 -- Copyright (C) Tika Software, Co.
  1405. ────────────────────────────────────────────────────────────────────────────────
  1406.  
  1407.      DataGen Reference
  1408.  
  1409.      File Specification
  1410.  
  1411.      To execute DataGen, the following files must be loaded:
  1412.  
  1413.      DG.EXE:        The DataGen program
  1414.      DG.DAT:        DataGen Source Data (Turbo Toolbox)
  1415.      IO.TPU:        Input/Output Subroutine Module
  1416.  
  1417.      If BTRIEVE format is selected, the files:
  1418.  
  1419.      BTRIEVE.DAT:   DataGen BTRIEVE Source Data
  1420.      TURxBTRV.TPU:    BTRIEVE Link Module for Turbo Pascal
  1421.  
  1422.      must also be loaded.
  1423.  
  1424.  
  1425.      Command Structure
  1426.  
  1427.      DataGen generates code from a modified ScreenGen source file. The
  1428.      #STATEMENTs utilized by the DataGen generator are listed by section.
  1429.      #STATEMENTs not recognized by DataGen, but which appear in the .sg
  1430.      file will produce the warning: ** ASSUMED COMMENT ** followed by the
  1431.      text of the source line.
  1432.  
  1433.      <Global Definition Section>
  1434.  
  1435.      #DATABASE - See definition in ScreenGen Reference.
  1436.  
  1437.      <Variable Definition Section>
  1438.  
  1439.      #DEFINE <variable>
  1440.      Generates a Turbo Pascal identifier called <variable> as a member of
  1441.      the data record <SOURCE_FILE>_structure. The record field will have
  1442.      the Turbo Pascal data type as indicated by #TYPE (or the default for
  1443.      the <variable>). If the <variable> is of #TYPE string, it's length is
  1444.      calculated as the length of the field defined in the <Screen Defini-
  1445.      tion Section>.
  1446.  
  1447.      #MENU <menu>
  1448.      The #DEFINEd variable will be generated as type byte.
  1449.  
  1450.      #PROMPT <menu>
  1451.      The #DEFINEd variable will be generated as type byte.
  1452.  
  1453.      ## <comment_list>
  1454.      Allows the user of DG to comment source code. <comment_list> is not
  1455.      transferred to the resultant Turbo source. ## also separates the
  1456.      <Screen Definition Section> from the <Variable Definition Section>.
  1457.  
  1458.      #INDEX
  1459.      Indicates that the #DEFINEd field will be a search key. The field must
  1460.      be of #TYPE string.
  1461.  
  1462.  
  1463.  
  1464.  
  1465.              DataGen Page 21 -- Copyright (C) Tika Software, Co.
  1466. ────────────────────────────────────────────────────────────────────────────────
  1467.  
  1468.      #TYPE [ String | Integer | Real ]
  1469.      Default: String
  1470.      parameter = String       : A variable of type string[] is generated
  1471.      parameter = Integer : A variable of type integer is generated
  1472.      parameter = Real         : A variable of type real is generated
  1473.  
  1474.      #NOTDATA
  1475.      No identifier is generated for this field.
  1476.  
  1477.  
  1478.  
  1479.  
  1480.  
  1481.  
  1482.  
  1483.  
  1484.  
  1485.  
  1486.  
  1487.  
  1488.  
  1489.  
  1490.  
  1491.  
  1492.  
  1493.  
  1494.  
  1495.  
  1496.  
  1497.  
  1498.  
  1499.  
  1500.  
  1501.  
  1502.  
  1503.  
  1504.  
  1505.  
  1506.  
  1507.  
  1508.  
  1509.  
  1510.  
  1511.  
  1512.  
  1513.  
  1514.  
  1515.  
  1516.  
  1517.  
  1518.  
  1519.  
  1520.  
  1521.  
  1522.  
  1523.  
  1524.  
  1525.  
  1526.              DataGen Page 22 -- Copyright (C) Tika Software, Co.
  1527. ────────────────────────────────────────────────────────────────────────────────
  1528.  
  1529.      APPENDIX A: Examination of IO.TPU
  1530.  
  1531.      function get_string(default, option_list) : string[255];
  1532.  
  1533.      Accepts:  default - string[255]
  1534.                option_list -  string[80]
  1535.  
  1536.      Returns:  string, max length 255, as the value of the function
  1537.  
  1538.      Function: get_string() presents the user with an editing buffer con-
  1539.      taining the default string. Using Cursor keys, the user may change or
  1540.      add characters to the buffer. get_string() returns the altered string
  1541.      as the value of the function.
  1542.  
  1543.      option_list is a string comprised of any of the following.
  1544.  
  1545.      \q   <query>
  1546.      The associated <query> is printed as a prompt to the user for entry of
  1547.      data into the field.
  1548.  
  1549.      \d
  1550.      Display only: no data is to be entered into the field.
  1551.  
  1552.      \af
  1553.      Auto Forward: Exit from the routine occurs when the number of charac-
  1554.      ters in the field surpass the allocated size.
  1555.  
  1556.      \ab
  1557.      Auto Back: Exit from the routine occurs if the user hits a backspace
  1558.      when the field is empty.
  1559.  
  1560.      \g
  1561.      Capitalize: Upon exiting, the first character in the field is Capital-
  1562.      ized.
  1563.  
  1564.      \u
  1565.      Uppercase: Characters are forced to upper-case.
  1566.  
  1567.      \xnn
  1568.      Goto Xpos: Field location is set to Xpos nn.
  1569.  
  1570.      \ynn
  1571.      Goto Ypos: Field location is set to Ypos nn.
  1572.  
  1573.      \lnn
  1574.      Length: The maximum length of the field is set to nn characters.
  1575.  
  1576.      \fxxxxxxxx
  1577.      Format string: Data is to be entered in a formatted fashion, based on
  1578.      the format string xxxxxxxx. xxxxxxxx may contain any non-blank charac-
  1579.      ters. At symbols (@) indicate location for character entry.
  1580.      \cx
  1581.      Valid characters:   Limits the keystrokes accepted for data entry into
  1582.      the field.
  1583.  
  1584.  
  1585.  
  1586.  
  1587.              DataGen Page 23 -- Copyright (C) Tika Software, Co.
  1588. ────────────────────────────────────────────────────────────────────────────────
  1589.                     x = '*' : Any Alphanumeric Character
  1590.                     x = 'i' : Numeric Character only
  1591.                     x = 'r' : Numeric and Period (.) for entry of floating
  1592.      point numbers
  1593.  
  1594.      \kxxxxxxxxxxxxxxxx
  1595.      Return Keystrokes: Sets the keystrokes indicating exit from get_str-
  1596.      ing(). xxxxxxxxxxxxxxxx is a concatenation of the following
  1597.      'cr'      return on           carriage return
  1598.      'uc'           up_cursor
  1599.      'dc'           down_cursor
  1600.      'tab'          tab
  1601.      'btab'         Backtab (Shift+Tab)
  1602.      'esc'               Escape key
  1603.  
  1604.      \vix
  1605.      Video in: Sets the video attribute for field data entry
  1606.      x='b'     bright (normal video)
  1607.      x='d'     dim (low video)
  1608.      x='r'     reverse (reverse video)
  1609.  
  1610.      \vox
  1611.      Video out: Sets the video attribute for field upon exit.
  1612.      x='b','d','r' (see \vi above)
  1613.  
  1614.      Examples:
  1615.      Chair := get_string( 'Wicker', '\qEnter Chair Type:\x10\y15\l30');
  1616.  
  1617.      1. Assign input to the string variable Chair. Default value is the
  1618.      character string 'Wicker'. String input is accompanied by the query
  1619.      'Enter Chair Type:'. Length of the string should not exceed 30. Input
  1620.      takes place at screen position xpos=10, ypos=15.
  1621.  
  1622.      Today := get_string( system_date, '\qEnter Date\f@@/@@/@@\x3\y5');
  1623.  
  1624.      2. Assign input to the string variable Today. Default value is the 6
  1625.      character string variable system_date. String input is accompanied by
  1626.      the query 'Enter Date'. The string is to be entered in a formatted
  1627.      manner defined by the format string '@@/@@/@@'. Input takes place at
  1628.      screen position xpos=3, ypos=5.
  1629.  
  1630.  
  1631.  
  1632.  
  1633.  
  1634.  
  1635.  
  1636.  
  1637.  
  1638.  
  1639.  
  1640.  
  1641.  
  1642.  
  1643.  
  1644.  
  1645.  
  1646.  
  1647.  
  1648.              DataGen Page 24 -- Copyright (C) Tika Software, Co.
  1649. ────────────────────────────────────────────────────────────────────────────────
  1650.      function get_menu( menu, menuhelp, default, option_list ) : byte;
  1651.  
  1652.      Accepts:  menu - string[255]
  1653.                menuhelp - string[255]
  1654.                default - byte
  1655.                option_list - string[255]
  1656.  
  1657.      Returns:  byte as the value of the function
  1658.  
  1659.      Function: get_menu() presents the user with a list of menu choices
  1660.      passed in the menu, and menuhelp parameters. The user may select the
  1661.      desired choice by highlighting it and pressing return, or by pressing
  1662.      the first letter of that choice. get_menu() returns a byte correspond-
  1663.      ing to the choice number selected by the user.
  1664.  
  1665.      The trick to using get_menu() is understanding the format of the menu
  1666.      parameter. It must be in the following format.
  1667.  
  1668.      '\1First Choice\2Second Choice\3Third Choice... \9Last Choice'
  1669.  
  1670.      A maximum of nine (9) choices may appear for each menu. Choices may be
  1671.      clarified in the menuhelp parameter which appears directly under the
  1672.      highlighted choice.
  1673.  
  1674.      '\1This is the First Choice\2And the Second Choice... \9No more
  1675.      Choices'
  1676.  
  1677.      The default parameter should contain the number corresponding to the
  1678.      selection you wish highlighted upon presentation of the menu.
  1679.  
  1680.      option_list is a string comprised of any of the following.
  1681.  
  1682.      \q   <query>
  1683.      The associated <query> is printed as a prompt to the user for entry of
  1684.      data into the field.
  1685.  
  1686.      \d
  1687.      Display only: no data is to be entered into the field.
  1688.  
  1689.      \kxxxxxxxxxxxxxxxx
  1690.      Return Keystrokes: Sets the keystrokes indicating exit from get_str-
  1691.      ing(). xxxxxxxxxxxxxxxx is a concatenation of the following
  1692.      'cr'      return on      carriage return
  1693.      'uc'                up_cursor
  1694.      'dc'                down_cursor
  1695.      'tab'                    tab
  1696.      'btab'                   Backtab (Shift+Tab)
  1697.      'esc'                    Escape key
  1698.  
  1699.      \vix
  1700.      Video in: Sets the video attribute for field data entry
  1701.      x='b'     bright (normal video)
  1702.      x='d'     dim (low video)
  1703.      x='r'     reverse (reverse video)
  1704.  
  1705.  
  1706.  
  1707.  
  1708.  
  1709.              DataGen Page 25 -- Copyright (C) Tika Software, Co.
  1710. ────────────────────────────────────────────────────────────────────────────────
  1711.  
  1712.      \vox
  1713.      Video out: Sets the video attribute for field upon exit.
  1714.      x='b','d','r' (see \vi above)
  1715.  
  1716.      \mxn
  1717.      Menu Xposition: n specifies the x screen coordinate at which the menu
  1718.      should appear.
  1719.  
  1720.      \myn
  1721.      Menu Yposition: n specifies the y screen coordinate at which the menu
  1722.      should appear.
  1723.  
  1724.      \pxn
  1725.      Prompt Xposition: If this option is included, get_menu() will echo the
  1726.      current menu selection at x screen coordinate n.
  1727.  
  1728.      \pyn
  1729.      Prompt Yposition: If this option is included, get_menu() will echo the
  1730.      current menu selection at y screen coordinate n.
  1731.  
  1732.      Example:
  1733.      Fruit := get_menu( '\1Apple\2Orange, '\1Big, Red and Juicy\2Sweet,
  1734.      slightly tart', 1,  '\qEnter Fruit Type:\mx10\my15');
  1735.  
  1736.      1. Assign input to the variable Fruit (type byte). The value of Fruit
  1737.      will be set to 1, or 2 based on whether the user selects 'Apple' or
  1738.      'Orange' from the menu. It will appear an Xposition 10 and Yposition
  1739.      15, preceded by the query 'Enter Fruit Type'. The default menu selec-
  1740.      tion is 'Apple', which will be highlighted when the menu appears.
  1741.  
  1742.  
  1743.  
  1744.  
  1745.  
  1746.  
  1747.  
  1748.  
  1749.  
  1750.  
  1751.  
  1752.  
  1753.  
  1754.  
  1755.  
  1756.  
  1757.  
  1758.  
  1759.  
  1760.  
  1761.  
  1762.  
  1763.  
  1764.  
  1765.  
  1766.  
  1767.  
  1768.  
  1769.  
  1770.              DataGen Page 26 -- Copyright (C) Tika Software, Co.
  1771. ────────────────────────────────────────────────────────────────────────────────
  1772.      function get_integer( default, option_list ) : integer;
  1773.  
  1774.      Accepts:  default - integer
  1775.                option_list - string[255]
  1776.  
  1777.      Returns:  integer, as the value of the function.
  1778.  
  1779.      Function: get_integer() allows the user to enter and change an in-
  1780.      teger. It has the same functionality as get_string().
  1781.  
  1782.      option_list is a string comprised of all of the options available
  1783.      within get_string(), plus the following.
  1784.  
  1785.      \lbnnnnnn
  1786.      Lower Bound: The integer entered by the user must be at least nnnnnn.
  1787.  
  1788.      \ubnnnnnn
  1789.      Upper Bound: The integer entered by the user must be at most nnnnnn.
  1790.  
  1791.  
  1792.  
  1793.      function get_real( default, option_list ) : real;
  1794.  
  1795.      Accepts:  default - real
  1796.                option_list - string[255]
  1797.  
  1798.      Returns:  real, as the value of the function.
  1799.  
  1800.      Function: get_real() allows the user to enter and change a real. It
  1801.      has the same functionality as get_string().
  1802.  
  1803.      option_list is a string comprised of all of the options available
  1804.      within get_string(), plus the following.
  1805.  
  1806.      \lbnnnnnn
  1807.      Lower Bound: The real entered by the user must be at least nnnnnn.
  1808.  
  1809.      \ubnnnnnn
  1810.      Upper Bound: The real entered by the user must be at most nnnnnn.
  1811.  
  1812.  
  1813.      Note: Both get_integer() and get_real() call get_string().
  1814.  
  1815.  
  1816.  
  1817.  
  1818.  
  1819.  
  1820.  
  1821.  
  1822.  
  1823.  
  1824.  
  1825.  
  1826.  
  1827.  
  1828.  
  1829.  
  1830.  
  1831.              DataGen Page 27 -- Copyright (C) Tika Software, Co.
  1832. ────────────────────────────────────────────────────────────────────────────────
  1833.      procedure scan;
  1834.  
  1835.      Sets:     in_keycode - keystroke
  1836.                in_chr - char
  1837.  
  1838.      Function: Accepts a keystroke from the keyboard. Sets the two global
  1839.      variables:
  1840.  
  1841.      in_keycode: a scaler variable of type keystroke with a value of:
  1842.  
  1843.      k_cr, k_escape, k_down_cursor, k_up_cursor, k_left_cursor,
  1844.      k_right_cursor, k_bs, k_tab, k_del, k_linefeed, k_ctrl_right,
  1845.      k_ctrl_left, k_home, k_end, k_ctrl_K, k_ctrl_Y,
  1846.      k_pgup, k_pgdn, k_backtab, k_ascii, k_invalid
  1847.  
  1848.      in_chr: char, that accepted by scan; Set to the ascii character when
  1849.      in_keycode = k_ascii.
  1850.  
  1851.  
  1852.      function format( format_string, format_shell, string_index ) :
  1853.      string[];
  1854.  
  1855.      Accepts:  format_string - string[255]
  1856.                format_shell - string[255]
  1857.  
  1858.      Returns:  string_index - byte
  1859.                string[255] as the value of the function
  1860.  
  1861.      Function: Using format_shell as a guide, format() returns a formatted
  1862.      version of the passed string as the value of the function.
  1863.      string_index is set to the character location of the last non-format
  1864.      character in the returned string.
  1865.  
  1866.      format_shell consists of a combination of @s and non-blank format
  1867.      characters. Examples of a valid format_shell are:
  1868.  
  1869.                @@/@@/@@  (Date)
  1870.                @@@-@@-@@@@    (Social Security Number)
  1871.                22-@@@@@@@@@   (Federal ID)
  1872.  
  1873.      Sample Call:        format('122269', 'H@@@@-@@@DF@@@', s_index );
  1874.      Returns 'H1222-69 DF' as the value of the function, and sets
  1875.      string_index = 8.
  1876.  
  1877.      function atoi( ascii_int ) : integer
  1878.  
  1879.      Accepts:  ascii_int - string representation of an integer;
  1880.      Returns:  integer, as the value of the function
  1881.  
  1882.      Function: Converts a string into the integer which it represents.
  1883.  
  1884.      Sample Call:        atoi('12')
  1885.      Returns the integer 12 as the value of the function.
  1886.  
  1887.  
  1888.  
  1889.  
  1890.  
  1891.  
  1892.              DataGen Page 28 -- Copyright (C) Tika Software, Co.
  1893. ────────────────────────────────────────────────────────────────────────────────
  1894.      function itoa( integer ) : string[]
  1895.  
  1896.      Accepts:  integer
  1897.      Returns:  string[] representation of integer as the value of the func-
  1898.      tion
  1899.  
  1900.      Function: Converts an integer into a string which represents it.
  1901.  
  1902.      Sample Call:        itoa( 966 )
  1903.      Returns the string '966' as the value of the function.
  1904.  
  1905.      function ator( ascii_real ) : real
  1906.  
  1907.      Accepts:  ascii_real - string representation of a real number;
  1908.      Returns:  real, as the value of the function
  1909.  
  1910.      Function: Converts a string into the real which it represents.
  1911.  
  1912.      Sample Call:        ator('16.35')
  1913.      Returns the real number 16.35 as the value of the function.
  1914.  
  1915.      function rtoa( real_number ) : string[]
  1916.  
  1917.      Accepts:  real_number - real
  1918.      Returns:  string[] representation of real_number as the value of the
  1919.      function
  1920.  
  1921.      Function: Converts a real number into a string which represents it.
  1922.  
  1923.      Sample Call:        rtoa( 11.44 )
  1924.      Returns the string '11.44' as the value of the function.
  1925.  
  1926.      function capitalize( in_string ) : string[]
  1927.  
  1928.      Accepts:  in_string - string[255]
  1929.      Returns:  string[] as the value of the function
  1930.  
  1931.      Function: The first letter of each word in string[] (separated by
  1932.      blanks) is capitalized.
  1933.  
  1934.      Sample Call:        capitalize('it was the best of times');
  1935.      Returns:       'It Was The Best Of Times' as the value of the func-
  1936.      tion.
  1937.  
  1938.      procedure set_cursor( setting )
  1939.  
  1940.      Accepts:  setting - byte (0/1)
  1941.  
  1942.      Function: setting = 0, cursor is turned off
  1943.                setting = 1, cursor is turned on
  1944.  
  1945.      procedure message( message, severity )
  1946.  
  1947.      Accepts:  message - string[80]
  1948.  
  1949.  
  1950.  
  1951.  
  1952.  
  1953.              DataGen Page 29 -- Copyright (C) Tika Software, Co.
  1954. ────────────────────────────────────────────────────────────────────────────────
  1955.                setting - byte (1-4)
  1956.  
  1957.      Function: Prints message along the foot of the screen. Set severity
  1958.      to:
  1959.                1: display the message
  1960.                2: display the message and beep
  1961.                3: display the message, beep, display Any Key Continues, and
  1962.      await user input
  1963.                4: display the message, Any Key Continues, no beep
  1964.  
  1965.      Sample Call:   message('Your PC is about to explode, please leave the
  1966.      room', 3);
  1967.  
  1968.      procedure video( attribute )
  1969.  
  1970.      Accepts:  attribute - byte
  1971.  
  1972.      Function: no_color:      do nothing
  1973.                bright:             Normal Video
  1974.                dim:           Low Video
  1975.                reverse:       Reverse Video
  1976.  
  1977.      The four video attributes listed above are defined as global con-
  1978.      stants.
  1979.  
  1980.      Sample Call:   video( bright );
  1981.  
  1982.      procedure writexy( xpos, ypos, attribute, show_string )
  1983.  
  1984.      Accepts:  xpos, ypos - byte
  1985.                attribute - byte
  1986.                show_string - string[80]
  1987.  
  1988.      Function: displays show_string at screen(xpos, ypos) using video at-
  1989.      tribute.
  1990.  
  1991.      Sample Call:   writexy(2, 20, dim, 'Howdy Doody');
  1992.  
  1993.  
  1994.  
  1995.  
  1996.  
  1997.  
  1998.  
  1999.  
  2000.  
  2001.  
  2002.  
  2003.  
  2004.  
  2005.  
  2006.  
  2007.  
  2008.  
  2009.  
  2010.  
  2011.  
  2012.  
  2013.  
  2014.              DataGen Page 30 -- Copyright (C) Tika Software, Co.
  2015. ────────────────────────────────────────────────────────────────────────────────
  2016.  
  2017.  
  2018.          ----------------end-of-author's-documentation---------------
  2019.  
  2020.                          Software Library Information:
  2021.  
  2022.                     This disk copy provided as a service of
  2023.  
  2024.                            Public (software) Library
  2025.  
  2026.          We are not the authors of this program, nor are we associated
  2027.          with the author in any way other than as a distributor of the
  2028.          program in accordance with the author's terms of distribution.
  2029.  
  2030.          Please direct shareware payments and specific questions about
  2031.          this program to the author of the program, whose name appears
  2032.          elsewhere in  this documentation. If you have trouble getting
  2033.          in touch with the author,  we will do whatever we can to help
  2034.          you with your questions. All programs have been tested and do
  2035.          run.  To report problems,  please use the form that is in the
  2036.          file PROBLEM.DOC on many of our disks or in other written for-
  2037.          mat with screen printouts, if possible.  PsL cannot debug pro-
  2038.          programs over the telephone, though we can answer questions.
  2039.  
  2040.          Disks in the PsL are updated  monthly,  so if you did not get
  2041.          this disk directly from the PsL, you should be aware that the
  2042.          files in this set may no longer be the current versions. Also,
  2043.          if you got this disk from another vendor and are having prob-
  2044.          lems,  be aware that  some files may have become corrupted or
  2045.          lost by that vendor. Get a current, working disk from PsL.
  2046.  
  2047.          For a copy of the latest monthly software library newsletter
  2048.          and a list of the 3,000+ disks in the library, call or write
  2049.  
  2050.                            Public (software) Library
  2051.                                P.O.Box 35705 - F
  2052.                             Houston, TX 77235-5705
  2053.  
  2054.                                 1-800-2424-PSL
  2055.                              MC/Visa/AmEx/Discover
  2056.  
  2057.                           Outside of U.S. or in Texas
  2058.                           or for general information,
  2059.                               Call 1-713-524-6394
  2060.  
  2061.                           PsL also has an outstanding
  2062.                           catalog for the Macintosh.
  2063.  
  2064.